home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 44 / Amiga Format CD44 (1999-08-26)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-10].iso / -in_the_mag- / basics / blitz / blitzfileid.lha / BlitzFileID / BlitzFileID.asc next >
Text File  |  1998-12-27  |  12KB  |  481 lines
  1. ; ASCII source version.
  2.  
  3. ; The tokenised version is in the dev/basic/BlitzFileID.lha
  4. ; archive on Aminet.
  5.  
  6. ; IMPORTANT : This needs Blitzlibs:amigalibs.res
  7. ; specified in the Compiler Options "Resident" box.
  8.  
  9. XINCLUDE "BlitzFileIDIncs.bb2" ; This is supplied in
  10.                                ; the archive, along with
  11.                                ; an ASCII version.
  12.  
  13. .TOP
  14. .
  15. ; BlitzFileID :
  16.  
  17. ; A set of functions & statements for using FileID.library
  18. ; By James L Boyd - jamesboyd@all-hail.freeserve.co.uk
  19.  
  20. ; FileID.library is (C) 1993-1998 by Oliver "Bloodrock" Lange
  21.  
  22. ; $VER: BlitzFileID v1.2 (27.12.1998) James L Boyd
  23.  
  24. ;----------------------------------------------------------------
  25.  
  26. ; Functions and statements included
  27. ;----------------------------------
  28. ; ( F = function ; S = statement )
  29. ;----------------------------------
  30.  
  31. ; CheckLib {}        F  - Checks availability of any library.
  32.  
  33. ; RecTypes {}        F  - Number of file types known by the
  34. ;                         fileid.library.
  35.  
  36. ; AllocFileInfo {}   F  - Allocates FI_FileInfo structure, ie.
  37. ;                         set library up to examine file(s).
  38.  
  39. ;                         MUST be freed by calling FreeFileInfo {}
  40. ;                         before quitting.
  41.  
  42. ; ExamineFile {}     F  - Examines file (duh)...will return
  43. ;                         an error code if something's wrong.
  44.  
  45. ; GetError {}        F  - Returns FileID's built-in error string,
  46. ;                         using the value from ExamineFile {}.
  47.  
  48. ; GetCustomError {}  F  - Returns programmer's own error string,
  49. ;                         using the value from ExamineFile {}.
  50.  
  51. ; FileTypeNumber {}  F  - File type ID number, eg. #FID_LHA,
  52. ;                         which is 71 - an LHA archive. The values
  53. ;                         are listed in BlitzFileIDIncs.bb2.
  54.  
  55. ; FileTypeName {}    F  - File type name, eg. "ZIP archive".
  56.  
  57. ; TypeFromNumber {}  F  - Returns file type string from number.
  58. ;                         You supply a valid fileid.library
  59. ;                         ID number, and it'll return the file
  60. ;                         type string.
  61.  
  62. ; FreeFileInfo {}    S  - Free FI_FileInfo structure allocated
  63. ;                         by AllocFileInfo {}. MUST be called
  64. ;                         before program ends!
  65.  
  66. ; Most functions have built-in "debugging" - they tell you
  67. ; if you haven't allocated a FI_FileInfo structure (ie called
  68. ; AllocFileInfo {} ) and put up a requester. This can only
  69. ; appear while your program's in development, so it won't
  70. ; ever appear to your user if it doesn't appear to you!
  71.  
  72. .USAGE
  73. ;-----
  74.  
  75. ; Simple usage of this set of functions :
  76.  
  77. ; 1) Check for the FileID.library on user's system,
  78. ;    by calling CheckLib {}. Quit if it's not there.
  79.  
  80. ; 2) Set up the library for use by calling AllocFileInfo {}.
  81.  
  82. ; 3) Use the library to examine the file, by calling
  83. ;    ExamineFile {}.
  84.  
  85. ; 4) Find out what the file is by calling FileTypeNumber {}
  86. ;    or FileTypeName {}.
  87.  
  88. ; 5) Repeat steps 3) and 4) for as many files as you like.
  89.  
  90. ; 6) Tell the program you've finished with the library
  91. ;    by calling FreeFileInfo {} - this is important!
  92.  
  93. ; See the demos for practical examples.
  94.  
  95. .
  96. .STATEMENTS
  97. ;----------
  98. .
  99.  
  100. .FreeFileInfo
  101.  
  102. ; Frees the FI_FileInfo structure if it's been set up
  103. ; by the AllocFileInfo {} function.
  104.  
  105. ; Example usage :
  106.  
  107. ; FreeFileInfo {}
  108.  
  109.   Statement FreeFileInfo {}
  110.     SHARED *FileInfo.FI_FileInfo
  111.     If *FileInfo
  112.       FIFreeFileInfo_ *FileInfo
  113.     Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  114.     EndIf
  115.   End Statement
  116.  
  117. .
  118. .FUNCTIONS
  119. ;---------
  120. .
  121.  
  122. .CheckLib
  123.  
  124. ; Returns pointer to library if successful (not useful!)
  125. ; or False (0) if library/version not available.
  126.  
  127. ; This is NOT dependant on FileID.library - you
  128. ; can use it in any program, for any library!
  129.  
  130. ; libv can only be an integer - no sub-versions!
  131. ; (OS choice, not mine!).
  132.  
  133. ; Example usage :
  134.  
  135. ; If CheckLib {"reqtools.library",38} = False Then End
  136.  
  137.   Function.l CheckLib {lib$,libv.w}
  138.   *lib.l=OpenLibrary_(&lib$,libv)
  139.     If *lib
  140.       CloseLibrary_ *lib
  141.     EndIf
  142.   Function Return *lib
  143.   End Function
  144.  
  145. .AllocFileInfo
  146.  
  147. ; Returns pointer to FI_FileInfo structure if successful,
  148. ; or False (0) if failed. Must be freed before program ends
  149. ; by calling FreeFileInfo {}.
  150.  
  151. ; Example usage :
  152.  
  153. ; If AllocFileInfo {} = False Then End
  154.  
  155.   Function.l AllocFileInfo {}
  156.     SHARED *FileInfo.FI_FileInfo
  157.     *FileInfo=FIAllocFileInfo_
  158.     Function Return *FileInfo
  159.   End Function
  160.  
  161. .ExamineFile
  162.  
  163. ; Reads start of file to try and determine type.
  164.  
  165. ; If you get any value returned which is NOT zero,
  166. ; an error has occurred - supply the value to GetError {}
  167. ; to find out what's wrong.
  168.  
  169. ; REMEMBER - you want it to return a false (0) value !!!
  170.  
  171. ; Example usage :
  172.  
  173. ; If ExamineFile {"C:Copy"} <> False Then Print "Error"
  174.  
  175. Function.l ExamineFile {fil$}
  176.   SHARED *FileInfo.FI_FileInfo
  177.   If *FileInfo
  178.   error.l=FIIdentifyFromName_ (*FileInfo,&fil$)
  179.   Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  180.   EndIf
  181. Function Return error
  182. End Function
  183.  
  184. .FileTypeNumber
  185.  
  186. ; Returns the file type's number (from the FileID includes).
  187. ; the result is of a word value.
  188.  
  189. ; Good if you don't need the string, if you just wanted
  190. ; to check a file was an IFF before loading, for example.
  191. ; ( eg. #FID_ILBM = 19 )
  192.  
  193. ; The constants (file type numbers) are listed in the
  194. ; BlitzFileIDIncs.bb2 file.
  195.  
  196. ; Example usage :
  197.  
  198. ; If FileTypeNumber {} = #FID_LHA           ; #FID_LHA = 71
  199. ;   Execute_ "lha x example.lha RAM:",0,0
  200. ; Else Request "","Not an lha file!","OK"
  201. ; EndIf
  202.  
  203. Function.w FileTypeNumber {}
  204.  
  205.   SHARED *FileInfo.FI_FileInfo
  206.   If *FileInfo
  207.     Function Return *FileInfo\FI_ID
  208.   Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  209.   EndIf
  210.  
  211. End Function
  212.  
  213. .FileTypeName
  214.  
  215. ; Returns string containing file type according to
  216. ; the result of ExamineFile {}.
  217.  
  218. ; DO NOT CALL THIS IF YOU GET AN
  219. ; ERROR CODE FROM ExamineFile {} !
  220. ; ExamineFile {} MUST return 0 before this is called!
  221.  
  222. ; YOU must check it! See the demo!
  223.  
  224. ; Example usage :
  225.  
  226. ; If ExamineFile {fil$}=0 Then Print FileTypeName {}
  227.  
  228. Function.s FileTypeName {}
  229.   SHARED *FileInfo.FI_FileInfo
  230.   If *FileInfo
  231.     Function Return Peek$(FIGetIDString_(*FileInfo\FI_ID))
  232.   Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  233.   EndIf
  234. End Function
  235.  
  236. .TypeFromNumber
  237.  
  238. ; Returns a string when given a file type number/constant,
  239. ; as listed in BlitzFileIDIncs.bb2.
  240.  
  241. ; Using RecTypes {} will give you the highest number
  242. ; available - use numbers from 0 to RecTypes {}.
  243.  
  244. ; See DEMO2 for a working example.
  245.  
  246. ; Example usage :
  247.  
  248. ; Print TypeFromNumber {#FID_LHA}
  249. ; (above line will print "LhA/Lharc archive")
  250.  
  251. Function.s TypeFromNumber {no.l}
  252.   SHARED *FileInfo.FI_FileInfo
  253.   If *FileInfo
  254.     Function Return Peek$(FIGetIDString_(no))
  255.   Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  256.   EndIf
  257. End Function
  258.  
  259. .GetError
  260.  
  261. ; Returns the fileID.library's built-in error string for
  262. ; the error which has occurred (a non-zero number returned
  263. ; by ExamineFile {} ).
  264.  
  265. ; Only call if you get a non-zero value returned
  266. ; from ExamineFile {} !
  267.  
  268. ; Example usage :
  269.  
  270. ; If error <> False Then Print GetError {}
  271.  
  272. Function.s GetError{}
  273.   SHARED *FileInfo.FI_FileInfo
  274.   If *FileInfo
  275.     error$=Peek$(*FileInfo\FI_Description)
  276.   Else Request "Programmer Error!","Programmer Error!||You haven't called AllocFileInfo {} !","Doh!"
  277.   EndIf
  278. Function Return error$
  279. End Function
  280.  
  281. .GetCustomError
  282.  
  283. ; Allows you to set your own error strings to be returned
  284. ; ONLY if ExamineFile{} returns a non-zero value.
  285.  
  286. ; Example usage :
  287.  
  288. ; If ExamineFile {"T:xx"} <> False Then Print GetCustomError {error}
  289.  
  290. Function.s GetCustomError {error.l}
  291.  
  292. If error = False
  293.   Request "Programmer Error!","Programmer Error!||You've called GetCustomError {} with no error code!","Abort!"
  294. EndIf
  295.  
  296. Select error
  297.  
  298. ; these are the values returned : just go through the
  299. ; Case sections changing the strings to suit your tastes...
  300.  
  301. ; From BlitzFileIDIncs.bb2 :
  302.  
  303. ; #ERR_FILOCKFAILED    = -1  ; couldn't get entry lock.
  304. ; #ERR_FIEXAMINEFAILED = -2  ; couldn't examine entry.
  305. ; #ERR_FIOPENFAILED    = -3  ; couldn't open file.
  306. ; #ERR_FIOUTOFMEM      = -4  ; out of memory.
  307. ; #ERR_FIREADERROR     = -5  ; file read error.
  308. ; #ERR_EMPTYFILE       = -6  ; filesize is ZERO.
  309. ; #ERR_NONAME          = -7  ; the passed filename is empty.
  310.  
  311.   Case -1
  312.     error$="Couldn't get DOS lock on file!"
  313.   Case -2
  314.     error$="Couldn't examine file!"
  315.   Case -3
  316.     error$="Couldn't open file!"
  317.   Case -4
  318.     error$="Not enough memory for operation!"
  319.   Case -5
  320.     error$="Error reading file!"
  321.   Case -6
  322.     error$="The file is 0 bytes in size!"
  323.   Case -7
  324.     error$="No filename supplied!"
  325.   Default
  326.     error$="Unknown error!" ; just in case ;)
  327. End Select
  328.  
  329. Function Return error$
  330. End Function
  331.  
  332. .RecTypes
  333.  
  334. ; Returns number of files current library version recognises.
  335.  
  336. ; Example usage :
  337.  
  338. ; Print "Number of types FileID knows : ",RecTypes {}
  339.  
  340.   Function.l RecTypes {}
  341.     notypes.l=FIGetHighID_
  342.   Function Return notypes
  343.   End Function
  344.  
  345. ;----------------------------------------------------------------
  346.  
  347. ; FreeFileInfo{}:End
  348. ; Uncomment the above line to see the built-in "debugging" !
  349.  
  350. ; Goto DEMO2
  351. ; Uncomment the above line to try the second demo.
  352.  
  353. .
  354. .DEMO
  355. ;----
  356. .
  357.  
  358. ; To use this set of functions, follow the four easy steps :
  359.  
  360. ; 1) Check for FileID.library's availability on user's system,
  361. ;    using CheckLib {} function - see CheckForLib label,
  362.  
  363. ; 2) Allocate a FI_FileInfo structure, using
  364. ;    AllocFileInfo {} function - see AllocStruct label,
  365.  
  366. ; 3) Examine the file(s) required, using ExamineFile {}
  367. ;    function (see .IDFile label), then use either
  368. ;    FileTypeNumber {} or FileTypeName {} functions to
  369. ;    get type of file.
  370.  
  371. ; 4) Free the FI_FileInfo structure before ending program,
  372. ;    using FreeStruct {} statement - see FreeStruct label.
  373.  
  374. ;----------------------------------------------------------------
  375.  
  376. ; Set up demo :
  377.  
  378. WBStartup
  379.  
  380. FindScreen 0
  381.  
  382. MaxLen p$=192 : MaxLen f$=192 : p$="SYS:" ; for file requester
  383.  
  384. ;----------------------------------------------------------------
  385.  
  386. ; First, we check for the FileID.library, at least v2 :
  387.  
  388. .CheckForLib
  389.  
  390. If CheckLib {"FileID.library",2} = False
  391.   Request "Information","You need FileID.library v2+ !","Abort"
  392.   End
  393. EndIf
  394.  
  395. ; We got this far, so we can allocate a FI_FileInfo structure :
  396.  
  397. .AllocStruct
  398.  
  399. If AllocFileInfo {} = False
  400.   Request "Information","Can't allocate FI_FileInfo structure!","Abort"
  401.   End
  402. EndIf
  403.  
  404. ;----------------------------------------------------------------
  405.  
  406. loop
  407.  
  408. fil$=ASLFileRequest$("Select file to identify",p$,f$)
  409.  
  410.   If fil$="" OR f$="" Then Goto quit
  411.  
  412. .IDFile
  413.  
  414.   If ExamineFile {fil$} <> False ; non-zero value returned?
  415.     Request "","Error : "+GetError{},"OK"            ; error!
  416.   Else Request "","File type : "+FileTypeName{},"OK" ; success!
  417.   EndIf
  418.  
  419. Goto loop
  420.  
  421. ;----------------------------------------------------------------
  422.  
  423. quit
  424.  
  425. ; Finally, we MUST free the structure :
  426.  
  427. .FreeStruct
  428.  
  429. FreeFileInfo {}
  430.  
  431. End
  432.  
  433. .
  434. .DEMO2
  435. ;-----
  436.  
  437. ; only works from compiler or CLI!!!
  438.  
  439. ; list all recognised file types :
  440.  
  441.   If FromCLI=0 Then Request "","Only to be run from CLI!","OK":End
  442.  
  443.   #SIGBREAKF_CTRL_C=1 ASL 12 ; Ctrl-C signal
  444.  
  445. If AllocFileInfo{} ; get a FI_FileInfo structure
  446.  
  447.   NPrint ""
  448.   NPrint "BlitzFileID - Listing all known file formats :"
  449.   NPrint ""
  450.  
  451.   Delay_ 50
  452.  
  453. ;----------------------------------------------------------------
  454.  
  455.   For a=0 To RecTypes{}
  456.  
  457.     NPrint "",Str$(a)+" : "+TypeFromNumber{a}
  458.  
  459.     ; quit on Ctrl-C, remembering to free FI_FileInfo structure!
  460.  
  461.     If (SetSignal_(0,#SIGBREAKF_CTRL_C) & #SIGBREAKF_CTRL_C)
  462.       NPrint "":NPrint "***Break - Click mouse!"
  463.       Pop For:FreeFileInfo{}:MouseWait:End
  464.     EndIf
  465.  
  466.   Next a
  467.  
  468. ;----------------------------------------------------------------
  469.  
  470.   NPrint "":NPrint "Click mouse!":MouseWait
  471.  
  472. FreeFileInfo{} ; free FI_FileInfo structure
  473.  
  474. Else Request "","Failed to allocate FI_FileInfo structure!","END"
  475. EndIf
  476.  
  477. End
  478. .
  479. .BOTTOM
  480.  
  481.